.TH std::basic_istream::operator>> 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary"
.SH NAME
std::basic_istream::operator>> \- std::basic_istream::operator>>

.SH Synopsis
   basic_istream& operator>>( unsigned short& value );               \fB(1)\fP
   basic_istream& operator>>( unsigned int& value );                 \fB(2)\fP
   basic_istream& operator>>( long& value );                         \fB(3)\fP
   basic_istream& operator>>( unsigned long& value );                \fB(4)\fP
   basic_istream& operator>>( long long& value );                    \fB(5)\fP  \fI(since C++11)\fP
   basic_istream& operator>>( unsigned long long& value );           \fB(6)\fP  \fI(since C++11)\fP
   basic_istream& operator>>( float& value );                        \fB(7)\fP
   basic_istream& operator>>( double& value );                       \fB(8)\fP
   basic_istream& operator>>( long double& value );                  \fB(9)\fP
   basic_istream& operator>>( bool& value );                         \fB(10)\fP
   basic_istream& operator>>( void*& value );                        \fB(11)\fP
   basic_istream& operator>>( short& value );                        \fB(12)\fP
   basic_istream& operator>>( int& value );                          \fB(13)\fP
   basic_istream& operator>>( /* extended-floating-point-type */&    \fB(14)\fP (since C++23)
   value );
   basic_istream& operator>>( std::ios_base& (*func)(std::ios_base&) \fB(15)\fP
   );
   basic_istream& operator>>( std::basic_ios<CharT, Traits>&
                                  (*func)(std::basic_ios<CharT,      \fB(16)\fP
   Traits>&) );
   basic_istream& operator>>( basic_istream& (*func)(basic_istream&) \fB(17)\fP
   );
   basic_istream& operator>>( std::basic_streambuf<CharT, Traits>*   \fB(18)\fP
   sb );

   Extracts values from an input stream.

   1-11) Extracts a value potentially skipping preceding whitespace. The value is
   stored to a given reference value.
   This function behaves as a FormattedInputFunction. After constructing and checking
   the sentry object, which may skip leading whitespace, extracts a value by calling
   std::num_get::get().
   12) Extracts a short value potentially skipping preceding whitespace. The value is
   stored to a given reference value.
   This function behaves as a FormattedInputFunction. After constructing and checking
   the sentry object, which may skip leading whitespace, extracts a long value lval by
   calling std::num_get::get(). After that:
     * If lval < std::numeric_limits<short>::min(), sets failbit and stores
       std::numeric_limits<short>::min() to val.
     * Otherwise, if std::numeric_limits<short>::max() < lval, sets failbit and stores
       std::numeric_limits<short>::max() to val.
     * Otherwise, stores static_cast<short>(lval) to val.
   13) Extracts an int value potentially skipping preceding whitespace. The value is
   stored to a given reference value.
   This function behaves as a FormattedInputFunction. After constructing and checking
   the sentry object, which may skip leading whitespace, extracts a long value lval by
   calling std::num_get::get(). After that:
     * If lval < std::numeric_limits<int>::min(), sets failbit and stores
       std::numeric_limits<int>::min() to val.
     * Otherwise, if std::numeric_limits<int>::max() < lval, sets failbit and stores
       std::numeric_limits<int>::max() to val.
     * Otherwise, stores static_cast<int>(lval) to val.
   14) Extracts an extended floating-point value potentially skipping preceding
   whitespace. The value is stored to a given reference value. The library provides
   overloads for all cv-unqualified extended floating-point types as the referenced
   type of the parameter value.
   Determines the standard floating-point type FP as follows:
     * If the floating-point conversion rank of /* extended-floating-point-type */ is
       less than or equal to that of float, then FP is float.
     * Otherwise, if the floating-point conversion rank of /*
       extended-floating-point-type */ is less than or equal to that of double, then FP
       is double.
     * Otherwise, FP is long double.
   This function behaves as a FormattedInputFunction. After constructing and checking
   the sentry object, which may skip leading whitespace, extracts an FP value fval by
   calling std::num_get::get(). After that:
     * If fval < -std::numeric_limits</* extended-floating-point-type */>::max(), sets
       failbit and stores -std::numeric_limits</* extended-floating-point-type
       */>::max() to val.
     * Otherwise, if std::numeric_limits</* extended-floating-point-type */>::max() <
       fval, sets failbit and stores std::numeric_limits</*
       extended-floating-point-type */>::max() to val.
     * Otherwise, stores static_cast</* extended-floating-point-type */>(fval) to val.
   15-17) Calls func(*this), where func is an I/O manipulator.
   18) Behaves as an UnformattedInputFunction. After constructing and checking the
   sentry object, extracts all data from *this and stores it to sb. The extraction
   stops if one of the following conditions are met:

     * end-of-file occurs on the input sequence;
     * inserting in the output sequence fails (in which case the character to be
       inserted is not extracted);
     * an exception occurs (in which case the exception is caught, and only rethrown if
       it inserted no characters and failbit is enabled in exceptions()).
   In either case, stores the number of characters extracted in the member variable
   accessed by subsequent calls to gcount(). If sb is a null pointer or if no
   characters were inserted into sb, calls setstate(failbit) (which may throw
   std::ios_base::failure if enabled).

   If extraction fails (e.g. if a letter was entered where a digit is expected), zero
   is written to value and failbit is set. For signed integers, if extraction results
   in the value too large or too small to fit in value, std::numeric_limits<T>::max()
   or std::numeric_limits<T>::min() (respectively) is written and failbit flag is set.
   For unsigned integers, if extraction results in the value too large or too small to
   fit in value, std::numeric_limits<T>::max() is written and failbit flag is set.

.SH Parameters

   value - reference to an integer or floating-point value to store the extracted value
           to
   func  - pointer to I/O manipulator function
   sb    - pointer to the stream buffer to write all the data to

.SH Return value

   1-16,18) *this
   17) func(*this)

.SH Notes

   For overload \fB(14)\fP, when the extended floating-point type has a floating-point
   conversion rank that is not equal to the rank of any standard floating-point type,
   then double rounding during the conversion can result in inaccurate results.
   std::from_chars() can be used in situations where maximum accuracy is important.

.SH Example


// Run this code

 #include <iomanip>
 #include <iostream>
 #include <sstream>

 int main()
 {
     std::string input = "41 3.14 false hello world";
     std::istringstream stream(input);

     int n;
     double f;
     bool b;

     stream >> n >> f >> std::boolalpha >> b;
     std::cout << "n = " << n << '\\n'
               << "f = " << f << '\\n'
               << "b = " << std::boolalpha << b << '\\n';

     // extract the rest using the streambuf overload
     stream >> std::cout.rdbuf();
     std::cout << '\\n';
 }

.SH Output:

 n = 41
 f = 3.14
 b = false
 hello world

   Defect reports

   The following behavior-changing defect reports were applied retroactively to
   previously published C++ standards.

     DR    Applied to          Behavior as published              Correct behavior
                      it was unclear whether overload \fB(18)\fP
   LWG 64  C++98      can only rethrow the                    all exceptions caught
                      std::ios_base::failure thrown by        can be rethrown
                      calling setstate(failbit)
                      overload (12,13) delegated the
   LWG 118 C++98      extraction to num_get::get,             a long value is extracted
                      but it does not have overloads for      instead of short or int
                      short and int
                      overload \fB(18)\fP only rethrew exceptions
   LWG 413 C++98      thrown while extracting                 corrected sb to *this
                      characters from sb, but characters are
                      extracted from *this
                      overload \fB(18)\fP behaved as a
   LWG 567 C++98      FormattedInputFunction                  it behaves as an
                      because of the resolution of LWG issue  UnformattedInputFunction
                      60
                      overloads (12,13) did not store the
   LWG 661 C++98      extracted number                        stores the number if
                      to value due to the resolution of LWG   no overflow occurs
                      issue 118
   LWG 696 C++98      value was unchanged on extraction       set to zero or minimum/
                      failure                                 maximum values

.SH See also

   operator>>(std::basic_istream) extracts characters and character arrays
                                  \fI(function template)\fP
   operator<<                     performs stream input and output on strings
   operator>>                     \fI(function template)\fP
   operator<<                     performs stream input and output of bitsets
   operator>>                     \fI(function template)\fP
   operator<<                     serializes and deserializes a complex number
   operator>>                     \fI(function template)\fP
   operator<<                     performs stream input and output on pseudo-random
   operator>>                     number engine
   \fI(C++11)\fP                        \fI(function template)\fP
   operator<<                     performs stream input and output on pseudo-random
   operator>>                     number distribution
   \fI(C++11)\fP                        \fI(function template)\fP
   read                           extracts blocks of characters
                                  \fI(public member function)\fP
   readsome                       extracts already available blocks of characters
                                  \fI(public member function)\fP
   get                            extracts characters
                                  \fI(public member function)\fP
                                  extracts characters until the given character is
   getline                        found
                                  \fI(public member function)\fP
   from_chars                     converts a character sequence to an integer or
   \fI(C++17)\fP                        floating-point value
                                  \fI(function)\fP
